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00020 00006 
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VALID 00022 PAGES 
DESCRIPTION 

Leap liiiplenientation Documentation 

LEAP COMPILER INITIALIZATION(LEPINI) 

Dec I arat i ons (coinpi ler) 

COnPlLE-TiriE STACK 

CGriPILE-TiriE STACK 

Compiling calls to LEAP runtimes: 

Compiling calls to LEAP runt imes(cont) 

Compiling calls to LEAP (con t) 

Compi ling FOREACH'S 

Compiling Foreach's (continued) 

COriPILATION OF FOREACH SEARCHES 

GLOBAL nODEL CONSIDERATIONS (compiler) 

LEAP RUNTin INITIALIZATION (LPINI) 

PRINTNAnES(COnPILER) 
PRINTNAnES( RUNTIME ) 
PRINTNAME DATA STRUCTURES 



These i tem-pr intname nodes consist of two words which 
Printname Runtime routines. 
DEL_PNAriE (item) - delete printname. Called to disassociate 
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The following will hopefully (someday?) Include all the 
important implementation information necessary for someone else 
to maintain the LEAP compiler routines and the LEAP runtime 
rout i nes. 
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LEAP COnniLER INITIALIZATION(LEPINI) 

liverij time the compiler is started, or restarted the routine 
GENINI is called to initialize the state of the world, including 
zeroing out all the variables declared in ZERODATA areas. 
GENINI calls LEPINI to do various initializations for LEAP. 

LEPINI does the following: 

1. Initializes Q-stacks (LOCST,nPSTAK, ITnSTK,nPQSTK) by either 
pushing a zero argument (nPSTAK,nPQSTK) to mark the bottom 
of the stack (to prevent underflow), or pushes and pops a 
dummy argument onto the stack (LOCST, ITMSTK) so that 

the address of the first stack entry can be kept so that 
the Q-stack may be used as a FIFO queue. 

2. Gets dummy semblks for NIL, PHI, and NULL_CONTEXT(see backtracking) 

3. Initializes the ITEHNO and GITEriNO cells. (Used to keep track 
of how many local and global items have been declared). 

4. Initializes LEAPSK to be an empty stack. 

LPNAHE: This is called from the productions to insert the predeclared items 
such as MAINPI, EVTYPI etc into the symbol table. This really should 
be done as part of RTRAN, but as RTRAN cannot allocate integer constant 
semblks, there is really no alternative. 
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Doc I arat i ons (coinp i I er ) 

I. Declaration of items, itemvars. 

Items and itemvars are declared in the standard way: the 
ty!:)e. bits ace collected by TYPSET and the symbol is inserted into 
the symbol tabic by ENTID. Whereas itemvars are normal variables 
and tl'ius i-jill have storage associated with them, items are considered 
to be constants. An integer constant is created for each item declared. 
The value of the constant is determinehd by the following algorithm, 

1, If the item is local (not global model item), which is 
dctcM-mined by the GLOBL bit not being on in BITS, increment 
ITEflNO and use the current value of ITEflNO for the item's 

nLimber. 

Note: to reserve space for predeclared items such as HAINPI, 
EVTYPI, the routine LPINI (called before every compilation) 
initial izes I TEmO to '10). 

2. If the item were global (GLOBL bit on in BITS) then decrement 
GITEdNO and use that value for the item's number. 

GlTEriMO is initialized to '7777 

"!. With the above number as parameter (current ly in ac A) call 
CREINT to got a integer constant semblk. Store the semblk 
j-)o inter in the ^^VAL2 in the semblk for the item. 

There is no actLial storage allocation done for i terns as , they are constants, 
i:(-inLi(jh of course the corresponding integer constants may be placed out 
if refnrecl to by other than "immediate" instructions. Itemvars are 
allocated in thie same manner as real or integer variables. 

I I- . Dec I ar a t i on o f se t s , I i s t s . 

Again the declaration is pretty standard. Type bits are collected 
into GITG by TYPGET and the symbol is inserted into symbol table by 
ENTID. Note that there is only a single parse token for both lists, and 
sets. The ty|;)e list is indicated by both the SET bit and the LSTBIT being 
on in the TBITS entry. Also when stacked on the compile-time stack (LEAPSK: 
se i:ielow), lists are denoted by having both the LPSET and LPXISX bits on 
in the left half of the compile-time stack entry. 

Allocation at the end of procedure. Because the SAIL runtime 
initialization must be able to find all statically allocated sets and 
lists these are allocated together and a loader "LINK" is put out so that 
the runtime leap i ni t i a I i zer (LPINI ) can find all static sets and zero them 
out. During initialization when the SAIL program is initialized (by SAILOR) 
tliese variables will be zeroed (set to NIL or PHI). 

Value set parameters must be copied on entry to a procedure (SETCOP) 
and must also be dea Mocated (SETRCL) on procedure exit, A better practice 
iiould seem to be that SETCOP be called by the calling procedure since it 
can often be determined that no copying is necessary as the set is a 
temporary. On exit from a recursive procedure sets must also be deallocated, 
This is done from inside the block exit code (runtime routine BEXIT) or 
(runtime STKUUD) used in goto's out of procedures), both routines use the 
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procedut-R desci-lptor (also called PD) to determine where the set locals and 
parameters are located on the stack. 

Uhen any LEAPish declaration or construct is seen the cell LEAPIS is made 
non-zero. This ui I I be used later to determine if LEAP nI M have to be 
initial i zed at runt ime. 
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r;aMPH£-TiME stack 

I. STITM (STGET) 

Whenever an item or i teiiivar (SET OR LIST) is scanned in an expression 
(not tlie left side of an assignment) the routine STITM stacks the semblk on 
an internal stack uhose current top is pointed to the cell LEAPSK. Outside 
of ["OREACI r s STITM will also generate code to stack the previous element on 
LEAPSK if any. The reason we defer generating the code that will stack the 
current element is two-fold: one this i temvar may be a reference parameter 
in which case we will not want the value of the i temvar but rather the 
address; two, sometimes certain expressions can be compiled into more 
efficient code if we wait(e.g i tmvrl^i tmvr2 can be compiled into a MOVE, 
MOVEM rather than a PUSH, POP). 

Note that we must keep track of which things in LEAPSK for which code 
has been emitted to stack them. Therefore in the left half of the LEAPSK entry 
is a bit STACKED which will be on if code to stack the entity has been emited 
and off if no such code has been emited. Other left half bits in the LEAPSK 
entry keep track of such important information as whether this is an item 
BxpressionCLPITM) or not (LPSET, LPXISX);if this is properly a retr i eva I (RETRY) . 
or constuct ion (CNSTR) expression. All expressions are possibly construction 
c5xpressions at compile time, but NEW cannot properly be part of a retrieval 
expression, ANY and UNBOUND are not properly construction expressions, but this 
i mpro|:)r i ety Is discovered only at runtime. 

Gthior left hand bits, are: BINDING which indicates this is a foreach 
local which has not yet been bound; BOUND indicating a foreach local which has 
been bound by a previous search; PIXED which is on for item constants or 
contents of some non-local i temvar (it is read only in if-expr,and case-expr 
its exact significance is beyond me); DUMSEM which is on if the semblk is 
a dummy and is on only if the thing was a temp which has been remopped; LPDNY 
on if a item from a bracketed triple of a derived set within FOREACH; LPNUL 
is on only for null sets and lists. Two other bits FBIND and QBIND are not 
put in iDy STITM but are in the left half of the LEAPSK entry to indicate 
a BIND i temvar or a ? i temvar respectively as in: 

if A®BIND X B ? z then ... 

Within a Foreach associative context ( indicated by the LPPROG bit being 
on in FF) , no code is emited by STITM to stack the elements of LEAPSK. This 
Is to enable better code to be emitted for certain searches involving 
bracketed triples, and derived sets. For example 

FGF^EACH X I x(S)[a®o=v] =z do 
is com(:)iled as if it were: 

FOREACH x,c| | [a®osv] = qA x^qsz do 

Ue could not simply stack x, then do the bracketed triple, then stack v because 
tl'in design of the foreach interpreter at runtime does not allow anything to 
he rcMiiembered on the stack (see the difficulties if x were on the stack and 

then the search a^osv failed). 

NOTE; Some of the runtimes return their values on the top of the stack 
(as opposed to the normal convention of returning values in AC 1). 
E. G. COP(list). The compiler will emit the code to call the routine, 
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aiirl I..J i I I t:)ush an entry onto LEAPSK with the STACKED bit on in the left half 
and a zei-o i-jght half where a seniblK would normally appear. 
(GRFJ BF'IN ancrDF-INA in the compiler). 
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COnPILE-TIflE STACK 

II. ITMF^EL - since STITfl outside of FOREACH's causes code to be em i ted 

i-ihicli i-iill cause the previous top of the LEAPSK stack to be 
stacked on the runtime stack, we often must short-circuit this 
by removing things from the LEAPSK. One such routine is ITMREL 
i-ihich Is used in item relations such as: 

i tmvrl= i tmvr2. 

ITMREL takes the top element of LEAPSK (causes code to be em i ted 
to pop it into an ac if STACKED) and puts the semblk into the 
parse stack for relational operations later. 

III. OKSTAC- often we must force the top element of LEAPSK to actually 

lie stacked on the runtime stack. For example: 

riAKE a®ositmfn(0,l,a); 

if lie. did not stack "o" before starting to process the itmfn, the 
iiou Id not be stacked until the second a was seen thus the 
parameters on the runtime stack would be in the order 
a,0,l,o,a instead of a, o, 0,1, a which is the correct order. 
Callincj OKSTAC causes code to be emitted to stack the last operand 
on the runtime stack if necessary. 

IV. STGHK - called by the macro STAKCHECK(#of parms) . 

This makes sure that the #of parms top entries of LEAPSK are 

stacked. Also makes sure collects the BOUND, BINDING bits 

to !:ie passed to the runtimes into the left half of the word 

BYTES, and will return in left half of 

ac A: FBINLl if any of the parms had FBIND or QBIND on; 

the AND of the RETRV,CNSTR bits so you can check for construction 

-retrieval failure; and the AND of the LPITM,LPSET,LPXISX bits 

BO that you can check if all args were items, or sets. 

This removes the top entries from LEAPSK, and updates ADEPTH since 

It knows that these stack entries will go away. This updating of ADEPTH 

is \'eri\ Important. If you have a routine which calls LEAP with 

leap expressions and arithmetic expressions you must either make 

sure ll'ie ai-lthmetlc expressions are calculated first, or you 

must restore ADEPTH before calculating them. See PUTINL for an 

example of the later. 

STCIIK is usually very simple. However certain foreaches cause 

very cGm|;i Moated things to happen. 

lor example: 

for each x | x@cop (setDsv do 

Ue have the situation when we call STCHK that x and v are not 
stacked luit copCsetl) is (SEE STITM above for reason why x was not 
stacked). Therefore we must emit code that will pop "cop(setl)" 
into a cor Imp and then push the three arguments onto the runtime 

stack. 
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V. LASCHK -called from case-expr, i f-expr 

As it is known to be called from outside an associative context 
it does not have to check certain FOREACH dependant properties, but 
ntherwise is equi va I ent (except for minor ac differences) to 
STAKCHECKCl). See STCHK above. 

VI. BNDITrKBNDLST) - these routines make sure the top entry of LEAPSK 

is of the appropriate type ITEfl (SET or LIST) and make sure the 
code has gone out that will stack that entity. Then the top entry 
of LEAPSK is removed. These routines are now called from the 
APPLY, SPROUT and REflOVE execs. 
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Corii|:)i I i nci calls to LEAf-' runtimes: 

Host calls to leap runtimes are made by loading ac 5 with 
a i-iorcl containing Borne flag bits in the left half and a routine 
index in tlie right half, followed by a PUSHJ P,LEAP. Inside the runtimes 
tl-iis index 1-1 ill be used in a branch table calculation. 

[■.lithin the compiler there is a marvelous macro called RUNTIM 
i-ihicl"i calculates the indices of the various runtime routines. 
To generate tl'ie |:)roper code to call a given routine, simply place 
the desired Ih of the flag word into the Ih of BYTES, move the index 
(RLINiin defines a symbol which may be used for the index, the symbol 
is "L" concatenated with the routine name) into ac A. And call either 
I EAPri or I.FAPC2. These routines will do an ALLSTO followed by generating 
node which will load ac 5 with the required flag word, followed by 
emitting a TIISHJ P,LEAP. LEAPC2 differs from LEAPCl in that it will add 
to the index in A the contents of the right half of BYTES. 

The routine STCHK described partially above, in addition to 
making sure that the arguments will get stacked, calculates the BOUND, BINDING 
Ltits for the attribute, object, and value positions of the flag word and 
stores these in the left half of BYTES. A routine offset is also calculated 
and (Dlaced in tiie rh of BYTES. Current I y though, this offset is only used 
foi" set or list sear'ches within foreaches. 

A macro to call LEAPCl or LEAPC2 exists and is called LPCALL. 
LPCALL takes three parameters (the last two being opt ional ) . The f i rst 
is the routine name, the second the location of an amount to be added 
to the primary routine index (see SETREL for example), and the third 
if present indicates that LEAPC2 should:.be called rather than LEAPCl. 

For an example of how these routines are used let us look at the compiler's 
exec routine for MAKE. 

STAKCHECK (3) ;nAKE HAS THREE ARGUMENTS 
LPCALL (HAKE) {GENERATE THE CALL TO LEAP 

POP J P, 

The macro STAKCHECK calls STCHK with the argument three. And LPCALL 
calls LEAPCl with ac a loaded with the value LflAKE. 

Other macros often seen are RETCHK and CONCHK which when 
called immediately after STCHK will verify that the arguments were of 
retrieval type, or constructive type (Actually this is done merely 
by chkccking the Ih of ac A) . 

Most of the leap runtime routines leave their result, if any on 
the runtime stack P. However others , notably LENGTH of set, ISTRIPLE etc. 
return their result in ac 1. A macro XPREP makes sure this register is 
available. It also loads ac D with the value 1 so that a call to the 
HARK routine will mark the value as being in ac 1. Therefore be careful 
not to destroy D or else restore it before calling HARK. 
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Uofii|:n I 1 ng calls to LEAP runt i mes (cont) 

Most of tl-ie compiler execs for generating calls to the runtimes 
ai-G fairly ntraight forward. Let us briefly go through them. 

MAK and ERAS are straight-forward, as are STIN, and ISTRIP. 

ISIT has to choose between two different alternatives depending 

on wliether any of the arguments were preceded by BIND or "?" indicaed 

bi.) the presence of the FBIND bit in the left half of A following the 

STAKCIIECK. 

STREL must first determine if the arguments are sets or items. 

if items tlien a call to ITMREL to move the second parm to the parse-stack 

foMoLied by a jrst to IREL in the standard relation handler. 

If tl-ie arguments are sets the LPCALL to SETREL 1 s generated. 

1 JEL 1 is s t r a i gh 1 - for war d . 

rUPGO, and LIPGO mark a q-stack (LORSET) to determine if a set or list 

is bcinq constt-uctcd. Then cause a ZERO to be pushed on the runtime 

stack (this |-)osition of the stack will be used by the runtimes to 

col lect the set or I ist). 

GUM calls either the li st--maker (LSThAK) or the set-maker (SIP) depending 

(Ml tiie. value of the top entry of the LORSET q-stack. 

srCNT-( lenqtli of set) is straight-forward. An optimization easily added 
Mould be to see if the argument is really a reference set or list, and 

do- the code 1 n- I i ne. 

;■ ) T I J N T - ( c o i:i o 1- set) i s s t r a i g li t - f o r w a r d , 

\:£ V I - c n V e r t a r- i t h m e t i c expression to i t e m 

Fhe of the arithmetic expression is "gotten" and then marked 
as an i temvar temp. The i temvar semblk is then placed on .the LEAPSK. 

F C V N - c n v e i- 1 i t e m t o i n t e g e r 

If the item expression is stacked it is popped off into an ac, 
and ti-ie ac is marked as an integer temp. If the Item expression is' 
a constant item the integer semblk for the item is placed Into the parse 
stack. Ott-)erwise code to get the item expression into an ac Is emitted 
and the ac is marked as an integer temp. 

STLGP -lop of set 

This takes a reference set argument (hurray for deferred stacking) 
and calls tlie routine FIRREF to emit code to load the address of the 
set arguent into ac 14. Otherwise it is straight-forward. 

STI'lIN, STINT, STUNI- the set operations are rather straight-forward. 

f'UTIN -Put i tern into set 

Uses FIRREF to get load the address of the set, otherwise It 
straightforward. 

PUTINL- put item in list before, after 

Must compute which of four routines to call depending on wheter 
last argument is an item or arithmetic expression, and whether 
BEFORE or AFTER. The routine LISTGT is called to call FIRREF with 
list argument which was cleverly removed from the LEAPSK by the 
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exec routine HLDPNT. 

REMXD - uses FIRREF but otherwise is straightforward. 

REPLCX - is straightforward except for the fact that the list argument 
was never placed on the LEAPSK because, of a hack in the 
product i ons. 
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Coiii|:!i I 1 ng calls to LEAP(cont) 

CVLS- convert list to set, vice-versa. Set to list merely changes 
tlie marking of LEAPSK. list to set requires a LPCALL, 

REnNF,LSSUB -arc exec routines which set up the necessary information 
for « onto the q-stack LENSTR. REFINF is called when the 
list or set argument is by reference so the semblk is stacked, 
LSSUB, is called when the set or list has been stacked and 
saves ADEPTH on the stack. A flag in the left half of the 
LENSTR entry indicates which type, REFINF, LSSUB or string inf 
is in use. The exec for inf will use this flag to call either 
the string inf. or LINE which handles the two different inf's 
for I i sts. 

SEL IP, SELSBL, are straightforward except for munging ADEPTH when 
dealing with STAKCHECK (see STCHK for motivation). 

LSTCAT is straigl'it-forward. 

NEUNOT, NEUART are straight-forward except that the type code for the 
new item is stored in the left half of BYTES before the LPCALL. 
The type code is calculated by the routine ITtlTYP. 

GELET ~ FIRST, SECOND THIRD are straightforward. 
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Goiiipi I ing FnRRACH'S 

Ac an oxaiiiple to l:)e used in the remainder of this section let us consider: 

i-GREACH ? X,Y,Z SUCHTHAT X®YhA aCY^B) aY®XsZ DO 

1 . I n i t i a I i z i ng the . f oreach. 

l-lhcn tl'ie FIDREACH is parsed, a new block is entered (see productions) 
and the exec routine EACH4 is called. EACH4 declares a local variable 
naniRrl "SCB...". This variable will be passed to the runtime leap 
initializer, and is used in the block exit code (see BEXIT, STKUUD in 
the runtinies) to indicate whether a f oreach must be exited. 
RACII4 causes code to be emitted which will push the address of 
11)1 B variable onto the runtime stack. 



II. 



eating tl'ie locals. 

Tlie local variables to this foreach are X,Y,Z. As the local list 
is being scanned by the parser, ENTITY or QLOCAL followed by 
ENTITY ar-e called "for each local parsed. These routines do 
several things: 

1. The LPFREE bit in the SB ITS entry of the i temvar semblk 
is turned on. This will remain on until a search is 
pei-formed or a matching procedure called which will 
bind this i temvar. STCHK is responsible for turning ■ 

it off. (Also turned off by ISUCAL for matching procedure 
actual parameters within FOREACH' s). 

2. The LPFRCH (for normal local s) ,FREEBD (for question locals) 
bit is also turned on in the SBITS word. 



3. The count of number of locals seen (LOCALCOUNT) is incremented 
and the new value is the satisfier number for this local. 
Note; so that the, backup will work efficiently when we 

are calling an associative search within a foreach we do 
not pass the address of the local variable that is being 
bound taut rather the satisfier number. This number will 
be used as an index to a table within the runtime FOREACH 
interpreter. The satisfier number is also passed to 
any search following the search which bound the i temvar 
as the value is not normally moved from the internal 
table to the core variable (see FRPOP below), 

4. A constant semblk for the satisfier number is obtained 

by calling creint and its pointer is saved in the Sva 12 entry of the 
local ' s semblk. 



5. The i temvar' s semblk is pushed onto a q-stack of locals 
called LGCST. This will be used at the end of the foreach 
execs to determine if searches to bind on the locals have 

been emi tted. 
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Goiii|:)i I i ng Foroach's (continued) 

III. Eni i 1 1 i nc) the ca I i to star t of FOREACH 

Uhen all the locals have been scanned and the SUCHTHAT is 
seen t|-ie exec routine FRCHGO is called. This routine does 
tl-)e f ol I owi nq; 

1. Turns on the LPPROG bit in the FF word. 

This bit tells everyone that a FOREACH associative 
context Is in progress. This will effect such 
things as whether the current value of a foreach 
local Is stacked or the satisfier number. See 
BOOLEAN expressions below. 

2. Emits an instruction which will load ac 14 with 
the address of the FOREACH satisfier block (below) 
The f i xup for this instruction is saved in SATADR. 

3. Emits the call to the runtime leap initialzer 

IV. The FOREACH satisfier Block. 

Passed to the FOREACH interpreter at runtime is the address 
of a block of data about the local itemvars. 

The fii-st word is a JRST to the instruction following the 

FORFACH (For use when the last search fai I s) . A fixup 

to this Insti-uct ion is placed in the LOOP block to be filled 

in later by the LOOP code. 

A word containing the value of LOCALCOUNT is emitted (that is 
i|-io total number of locals and question locals for this FOREACH). 

.Tlip yeiiil-jlks for each local i temvar (obtained from LOCST) are 
Ins|3ecte(;l and a word containing the following is emitted. 

In tlin addi-ess portion of the word (index field and RH) the 
adcirosG of the local is placed (This will be picked up by a 
HUVLI (i> at runtime so the indirect bit must be off). 

In tlie left half the bits POTUNB for question locals, and 
I'lPPAnri If this local is a formal question parameter to a 
matching pirocedure (These are necessary since interpretation 
III I I l:ie done at runtime on these special itemvars). 

Ue have not been totally truthful when we talked about the 
address portion of the word to be emitted. Consider the following 

RECURSIVE PROCEDURE FOO; 
BEGIN ITEHVAR BAZ; 

PROCEDURE ZORK; 

BEGIN FOREACH BAZ | ... 

END; 
END; 
In this case the address of BAZ is not simple to compute as a 
display i-eglster Is required (see up-level addressing elsewhere) 
Tiierefore In this case, the word we will emit will (in addition 
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to any other LH bits) have the CDISP (calculate display) bit on. 
In the right half will be the normal stack offset, and in the 
INDEX field will be the difference between the current display 
level and the display level where the i temvar was declared (in 

thi s case 1) . 
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nOdPILATION OF FOREACH SEARCHES 
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[GLOBAL MODEL CONSIDERATIONS (compiler) 
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['RlNTNAriES (COMPILER) 

Until n "REQUIRE n PNAMES" statement is scanned the compiler 
,r:.c:.umcs that no |;irintnamG initialization is required and any items 
declared i-iili not receive initial printnames. 

Ulien tj-ie require statement is encountered it calls the routine 
I-'MAH (iiitl-iin the source_file LEAP). PNAII sets the variable PNMSU to 
0. r'NflSW i-ias original ly initialized to be -1 to indicate no printnames 
Mere requested. Prom here on it will contain the number of items with 
initial printnames. The count n from the require statement is placed in 
i|-H-:! variable PNAMNO which will later be a part of the space allocation 
l-)loc:k at i-untimc, PNAM sets up a Q-stack (a push down list) and 
records the head (bottom) of this list in the variable PNBEG. The top 
of tliis Gtack will stay in the variable PNLST. This Q-stack will 
contain entries whose left half is the i tern number and whose right 
lialf is the Bemblk pointer for the string constant corresponding to the 
1 teiiiG name. 

Prom then on everytime an item declaration is scanned the following 
things are done within the ENTID routine: 

1. PNUSU is incremented, 

2. A string constant the same as the item name is 
generated. 

3. A word containing the item number in the left half and 
the semblk pointer for the string constant in the right 
half, is pushed onto the Q-stack PNLST. 

At the end of the compilation within the routine DONES the 
printname initialization block is put out. First the program counter 
(which corres|:)onds to .the address of this block) is placed in PINIT 
(corresponding to l^PINIT in the space allocation block at runtime). Then 
the number of^pnamcs to be initialized is put out, followed by one word 
per pname coirtaining the item number in the left half and the address of 
the string constant for the pname in the right half. 

BUG!!! String constants may be used as comments at statement level. To keep 
from keeping' constants used only as comments around in the compiler the 
string comment handler will try to get rid of unused constants. Therefore 
if tlie fi^^up) chain of a string constant used as a string comment is empty 
tl-ie semblk'. wl I I be reclaimed. This will cause problems if the string was 
also used as. an initial pname, as the reference to the constant is not 
emitted until the end of the program. Thus we may find the semblk deleted 
or used for .something else. There should be some way of indicating in the 
semblk that even though the fixup chain is empty the constant is still in 
use. Note this problem also occurs for blocknames. 
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|-'RINTNAriES( RUNTIME ) 

A string called a prlntname (often refered to as a pnanie) may 
be riDsociatcd i-i i th a given item at runtime. Primitive actions on pnames 
incluclG dLinamicalki associating a printname with an item (NEU_PNAI1E) , 
cieletiiiq the printname of an item (DEL_PNAME) , finding the unique item 
ult|-i a qiven t-irintname (CVSI), and finding the printname of a given item 
(CVIS) . 'NOTE; an item may have at most a single non-null printname, and 
no ti-io distinct items may have the same printname. 

f ■* I- i n t n a m e i n i t i a I i z a t i o n ; 

I tcmG declared following a REQUIRE n PNAMES compiler statement, 
hdve initial printnames which are the same as their names. For example 
i f the f I I oil i ng dec I arat i on f o I I owed the requ i re: 

ITEM X; 

the printname of Item X would initially be "X". 

riurinq the initialization of the SAIL runtime environment 
a LEAP Initialization rout I ne(LPINI ) is called. This routine in turn 
callG tl-ic printname I ni 1 1 a I I zat I on routine INTNAM. The parameter to 
ININAM is contained in AC A and Is the address of a printname 
ini i I hI i;.,:cM. Ion lilock. This address was obtained from the space allocation 
iilock nntfii lU-'INIT. NOTE: for each separately compiled SAIL program there 
is -;p,:ir.r-/,:illncatIon blocl^ which includes such information as how many 
i toiiifj were "REQUinED" , the user's estimate of the number of pnames he 
111 I I use, etc. AM the space allocation blocks of programs loaded together 
rd-e linked Ih) means of the LOADER link command. 

The format o f the pr i ntname I n i 1 1 a I 1 zat i on b I ock is:' 

(First word) ■¥■ number of pnames * (may be zero) 

* to be Initialized ^ (<0 if no REQUIRE statement) 

:k Itemno, addr(str) * (one word for each pname 

;i.;5i<:|;:)f;*>i<>t;5i<:fc>f:***H<****>k** tO be Initialized) 



INTNAM calls NEW. PNAME for each pname to be initialized with the item 
numli'er from the left half and the string whose address is contained 
in tl-ie riciht half of the printname initialization block entry. 
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f'RINTNAriE DATA STRUCTURES 

The strings representing tlie printnanies are stored in the 
ritandard SAIL str'lng space (thus unfortunately not al lowing shar i ng, 
bi| use of thn global segment, of printnanies between jobs), k 
SAIL string variable is represented by a two word string descriptor: 
the first word containing the information such as the length of the 
Gtrinq and the. string id; the second, containing a byte pointer 
pointing to the first character of the actual string. For the 
string garl:.)age collector to worl^ correctly, It must be able to access 
all such two-word string descriptors. He could, of course, have a list 
of all the descriptors in use and have the garbage collector use it 
to access the. prlntnames. However, such a list would be relatively 
nxpensivn to maintain on deletion of prlntnames, as we would have 
to search down it to find the appropriate descriptor to delete when 
i-ie removed a printname. It therefore seems better to allocate one or 
more string arrays from which we will allocate individual descriptors 
for pnamos, and simply have the address of these string arrays on the 
Game list (ARYLS) as the addresses of the string arrays which are 
the da turns of i tems. 

On initialization of the pname structure, we allocate a string 
an-ai), tl'ie Gizq of which is the maximum of the "n" in the "REQUIRE 
n PNAIILS" statements of all the separately compiled SAIL programs 
which arc iDcing loaded together to form a single job ( if that number 
is less that S0, the string array's size Is 50). We form a list 
of the individual string descriptors which are not in use. The link 
[iQinting to thie next available descriptor is contained in the seconds 
word of" the current descriptor. These string descriptors are also 
used bg datums of STRING ITEHs. NOTE: because the string garbage 
collector ignores all string descriptors whose first word is zero, we 
do not have to worry about the garbage collector interpreting the 
links as byte pointers to actual strings. The address of the first 
available string descriptor is placed in the left half of the 
LIAGHP word of the user table (GOGTAB) . Thus we have a the following 
bU-uctui-e: 
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j --> list of string arrays 



-lASHP 



initial string array 



NOTE: The links to the two-word blocks point to the second word 

to confoi-iii wi th the SAIL convention that the address of a string 

variable is the address of the second.. word of the two word 
descriptor. 

Tho most coiiinion operation to be preformed on items and their printnaiiies 

is anticipated to be lookup: that is given an item find its printnanie and 

vice-versa. To be able to perform this lookup In a reasonable time we 
use a hash table (scatter storage) technique. 

There are actually two hash tables: one for items; one for pnames. 
It tui-ns out by use the ha If word instructions we can have the two tables 
live in the aanie block of core. The item hash table is in the left half 
nords of the block, and the string hash table is in the right half words 
nf ll-ie block. The address of this block (whose length is PHASLEN, currently 
net to 128 doc i ma I) is contained in the right ha If word of the HASHP entry 
of the user tal:)lo (recall that the address of the head of a list of 
available string descriptors is in the left half of the HASHP entry). 

Now suppose that we are given an item and are asked to find its 
printnamc. First we compute the hashcode from the item (currently this 
Ig siniplq done by "AND"ing the item number and PHASLEN-1), We then 
add this^ hashcode to the loase of the hashtable (right half of HASHP). 
This gives us the location containing the address of a confl'ict list 
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of nocios of item prlntnanie pairs wiiose item numbers hash to the same value. 
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These i teiii-pr i ntnaine nodes consist of two, words which 
are logically divided into 4 different fields: the item number; 
the link to the next node in the item conflict list; the address 
of tl-ie tuo uord string descriptor for the;;l6name; and the link 
to tho next node in the string conflict list. 



r (N .T^ .^ .T'' 'T' ■T' "TN 'T^ ''T' 'T* "T^ "T*" "T* •T* 'T* "T^ "T^ 

1^ ?!> 'T' 

* i tern no, >k i tem I ink ^ 

* * * 

-T' ■T* "T* 'T*' 'T" •T' 'T" ■T' 'T* ^ ■T> 'T' 'T' ♦T' 'T' 'T' "T* "T* "T* 'T' 'T' 'T* "T* 'T' "T" 

■4^ >K' >i< 

* addr. str.* str. I ink >n 

* * >K 



TlK'.fB is one of these nodes for each pr i ntname-i tem in existence. 

Let us continue with our search for a pname given an item number. 
We now have the address of the first node in the item conflict list. 
Lie cfieck to see if the item no. within the node is the one 
i)|-inf::F< printnanie is desired. If it is the same we return the string 
IDolntod to hy the lefthalf of the second word of the node. If not 
i-ie ok'tain the address of the the next node in the item conflict 
list from the right half of the first word in the current node 
under examination. i4e continue with this technique until we either 
iind the node whicli corresponds to the given item number or we 
i-uri out of nodes on the conflict list (this is indicated by a 



: e I' o 



ink field. If we exhaust the conflict list then we know 



liiat tl")er-e is no printname for the given item. 

Tl'if! seareli for tl'ie item with a given string name is similar. We form 
a liashcode from the string. Use that code as an index into the string 
hasivLab I e. Lr om this we obtain the list of nodes whose printnames 
hash to I he same value. Ue search down this list until we find a 
iiodt.: i.iiil'i I lie same string as we have and return the item number or 
lie exliaust the list and thus know that there is no item with the 
fLiven sti-ing as its |:)rintname. 
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■;VSI (str ing,ef lag) - Convert string to item. 

Forms hasl"icocle from string. Searches down appropriate 
conflict list for a node pointing to the same string 
as the parameter string. If found it sets the variable 
flag to "FALSE" and returns the appropriate item number as 
found in the left I'lalf of the first word of the node. If 
sucl'i a node is not found then CVSI sets the variable 
flag to "TRUE" and returns a garbage resu I t in accumulator 
1. the calling sequence from tlie user's program is: 



PUSH SP,i-jordl 
PUSH SP,i.Jord2 
PUSH P, [FLAG] 
PUSH J P,CVSI 



first word of string descriptor 
second word of string descriptor 
address of flag variable 
ca I I rout i ne . 



CVIS {item,@flag) ~ Convert item to string. 

f-orms hashcode from item number. Searches down appropriate 
conflict list for a node which contains the parameter item 
numl.'ier in the left half of its first word. If such a node 
is found it sets the flag to "FALSE" and pushes the two 
word string descriptor pointed to the left half of word2 of 
the node, onto the string stack (SP). If not found the NULL 
string is pushed onto the SP stack, and the variable FLAG 
is set to "TRUE" to indicate there was no printname for the 
gi VGn i tern. 



'he calling -sequence is! 

PUSH P, [item no.] 
PUSH P, [FLAG] 
PUSH J P,CVIS 



; i tern 

; address of flag variable 

;cal I routine 
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[lELJ-NAMl'. (Itciii) - delete printname. Called to disassociate 
and item and its printname. It is a noop if the item 
has no (irlntname. First of all, the item hashcode value 
is fnriiied from the item number. This value is used as 
an index into the I'lash table thus yielding the 
addr-esG of the conflict list of nodes whose items hash 
to the CMamc value. This list is searched for a node whose 
i teiii entry is the same as the parameter. If no such node 
is found tt')en DEL_PNAnE simply returns. If the node is found, 
tl'ie node is then deleted from the item conflict list. The 
string pointed to by string entry in the node is temporarily 
caved on the string stack. The first word of the 
two iiorcl string descriptor is zeroed so that the string 
yarbage collector will ignore that descriptor. The address of 
thie liead of the list of available string descriptors ( contained 
in tl-ie left lialf of i-IASHP (USER) ) is placed in the right half 
of the cecond word of the newly available string descriptor and 
the address of this descriptor is placed in the left half of 
IIASHP(USER). Thus we have linked the newly freed string descriptor 
on 1 t he list of available string descriptors. 

Wg now must remove the node from the string conflict list 
He do this by forming the hashcode from the string which we have 
temporarily placed on the top of the string stack. Ue then 
chain down the string conflict list thus selected until we find 
tl'ie node we wish to delete. After deletion we now link the node 
onto the free list of two-word blocks, FP2(USER), 

Ca I I i ng sequence; 

PUSH P, [item no.} 
PUSH J P,DEL.PNAnE 

NEN_PNAriE ( i tern, str ing) - give an item a new printname. First we check to 
see if printnames have been initialized. That is, if the hash 
table has been allocated. If not initialized we call the routine 
INITNn to do the allocate the table. Next we call the routine CVIS 
to see if the item already has a printname. If it does then we see 
if the oldname is the same as the new one in which case we simply 
i-eturn. If the names are different we issue a warning message to 
the user, then call DEL.PNAME to remove the old pname. Now we know 
tl'iat the item has no printname. We must now make sure that the new 
name is not the printname of some other item. We do this by calling 
CVSI. If CYSI tells us that the string is already in use as a pname 
we give an error message to the user. We now know that the 
printname does not already exist. We take an available string 
descriptor by calling the routine SDESCR (which will allocate a 
new string array and link them up if there are no more available). 
The string descriptor corresponding to the pname is placed in the 
string descriptor obtained from SDESCR. We now get a two word free 
to serve as a node for this pname-item binding. We place the 
address of the string descriptor into the left half of the 
second word and the item number in the left half of the first word. 
Ue then hash the item number to obtain the address of the item 
conflict list and link the node onto the list as its first element. 
Similarly we link the node onto the appropriate string conflict 
I i st. Fi nal ly we return. 
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Ca 1 I i ng sequence; 



PUSH P, [item no.] 

PUSH SP,wordl of string descriptor 
PUSH SP,word2 of string descriptor 
PUSH J P,NEU.PNAnE 



